Shareware Grab Bag/Shareware Grab Bag.iso/001/popt.arc/P-OPT.DOC

Text File | 1987-04-29 | 18KB | 410 lines

                                 P - OPT
                                 v. 1.0
                       " Power Tools for Power Users "

                               By Gizmo Mike
                            (C) InfoSoft, 1987
                     The Information booth [phone]

     1.0   Introduction

      P - OPT is a PROCOMM command file optimizer and a whole lot more!
    What it will do for you is read a PROCOMM command file and optimize it
    for speed at runtime.  As procomm executes a command file, it reads every
    single byte much as an interpeter would.  While using the 4 letter
    abbreviations would speed up execution, it makes lengthy source code
    harder to read and modify.

      P-OPT will allow you to comment liberally in the original command file,
    then optimize it for speed.  This leaves you with 2 "versions" one with
    comments and such for future modifications, and another streamlined for
    fast, Fast, FAST, FASTEST execution at runtime.

      Basically, when run, P-OPT will read the specified command file, then
    optimize it by removing any lines that are totally remarks, strip remarks
    from other lines, strip trailing and leading spaces (ie it undoes
    indentation) then substitutes the short for for the commmand key word
    (MESSAGE becomes MESS, TRANSMIT becomes TRANS etc).


     1.1  Execution Time

      Granted, this is not for your average 5 line command file, but for
    larger intricate command files, it can help out a bunch.   VERSA, a
    PC Pursuit navigator, in its commented form is 915 lines, 36K.  Once run
    thru P-OPT, is shrinks to a lean and mean 658 lines, 10.7K.  And it is
    fast!  On an AT the process takes 23 secs, on a PC a mere 72 secs!


     1.2   Basic P-OPT functions

       Functions supported in P-OPT, mainly thru the use of meta commands:

    * Optimize PROCOMM scripts for optimimum run time.
      - Remove leading space from quoted strings.
      - Substitute 4 character form of all, most or some PROCOMM command
        words.
      - Truncate labels to the first 8 characters and a ":".
      - Truncate label references (GOTO LONGLABEL) to first 8 characters.
      - Remove blank lines from source.
      - Strip trailing spaces and remarks from source.
    * Produce printed output directly from P-OPT
    * Allow for remarks of special significance to remain in the optimized
        output.
    * Assign text strings via meta-commands to title and label the output.
    * Produce a crossreference, of optimized code, with a SOURCE line
      number.


     2.0   Command line syntax

       A few parameters are passed to P-OPT from the command line.  P-OPT's
    command line arguments ARE POSITIONAL!

    Syntax:  P-OPT  source[.CMD] target[.OPT] [/c | /nc ]


     2.1   Command line parameters

       The first parameter passed tells P-OPT what source file to optimize.
    You can enter the extension of .CMD or not, but P-OPT will look for
    source.CMD.  If it does not exist it will tell you.

      The second parameter is the output file name.  Here, you can enter
    the extension of .OPT or not, but P-OPT will output to target.OPT.  If
    the file exists, P-OPY will ask you if you are sure that you want to
    overwrite it.  If you do not, if will prompt you for a new filename.
    If you wish to output to a printer, then use LPT1 or LPT2 (whichever is
    appropriate) as the output filename.

       The final parameter allows for color (/C) or blah non color (/NC)
    screen display at runtime.


     3.0   Meta Command Intro

      Additionally, P-OPT offers a set of meta-commands.  Meta-commands, if
    you are not familar with them, are intructions to an intermediate program
    as opposed to the final program.  Here a meta-command is a way of sending
    an instruction to P-OPT (as opposed to PROCOMM) in the script file.

      In this case, the meta-commands allow you to send instructions to P-OPT
    as it is optimizing your source file.  Other meta-commands allow you to
    preserve certain strings that might otherwise be stipped from the source
    file.


     3.1 Meta-Command syntax

      P-OPT metacommands all begin with a PROCOMM remark character (";") and
    end with a colon ":" and are 8 characters.  The ";" prevents the meta
    commands from interfering with PROCOMM, and the rest makes it easy for
    P-OPT to recognize the line as a meta-command

    The metacommands currently supported are:

    ;$TITLE:       -   The title or name of your script file
    ;$SUBTL:       -   A date or whatever tickles your fancy
    ;$AUTHR:       -   List the author of the script file
    ;$VERSN:       -   A version number if you wish

    ;$REMRK:       -   A remark to remain in target file

    :$PGSIZ:       -   Number of lines to print per page
    ;$PAGEF:       -   If output is to LPTx, send unconditional Form Feed
    ;$LNCNT:       -   Yes/No (1/0) switch for line numbers



    3.2  Meta-Command usage

      Basically, P-OPT will not strip meta-commands from the source file,
    unless told to.  This allows you to place your name, a subtitle, a
    version etc in a script file and not have P-OPT strip it from the source
    file.  A meta-command MUST begin in column 1 of the source file or it too
    is stripped from the source and may as well have been a simple PROCOMM
    remark.
      Additionally, the ;$REMRK: meta-command will not be stripped even if
    the ;$MCMDS: switch is off.  This makes it additioanlly helpful when used
    right.

      Right:
    +----------------------------
    |;$REMRK:  Be careful not to change S6 !!
    |ASSIGN S6="foo-bar"

     Wrong:
    +--------------------------------------
    |ASSIGN S6="foo-bar"         ;$REMRK:  Be careful not to change S6 !!

      Additionally, the ;$REMRK: meta-command will not be stripped even if
    the ;$MCMDS: switch is off.  This makes it additioanlly helpful when used
    right.


    3.3   Printing with Meta-Commands

      If you are outputting to a printer via P-OPT, the last 4 meta-commands
    allow additional printer control: the first two control page length
    and compressed or normal type.  If you have an intricate routine or
    subroutine going, you can force a formfeed at a specific point that makes
    sence to you with ;$PAGEF:.  In so doing, the line counter internal to
    P-OPT will reset to 0.  This means that the next formfeed will be
    however many lines later that you have $PGSIZ: set to.


      Finally, P-OPT will place the author, title, subtitle and version meta-
    command assignment at the top of each page, as well as a page number.
    For this reason, if you attempt to make multiple $SUBTL: assignments,
    only the last one would be printed. Eg:

     Command file:                        Printed output:
    ;$TITLE: My command file              My Command File
    ;$AUTHR: Gizmo Mike                   Gizmo Mike
    ;$VERSN: Version 1.01                 Version: 1.01
    ;$SUBTL: A fine program               I wrote today
    ;$SUBTL: I wrote today


     This is not a glitch but a compromise made for speed, but adds an
    additional benefit explained later.



    3.3.5  Printer meta-command placement

       The 3 printer meta-commands, if used, should be placed in the very
    beginning of the source file after $AUTHR:, $TITLE:, $VERSN: and $SUBTL;
    If none of the printer meta-commands appear in the first fifteen lines
    of the source, the defaults are used and suprious results may occur.
    Printer meta-commands are ignored and stripped when outputting to disk.


    3.4   Disk File output

      Of cource you will not always output to a printer.  If output is to a
    disk file, the printer related meta-commands are ignored, but they still
    remain in the target file.  However, the others will come in handy.
    In the top portion of the source you can put a copyright notice, a
    version etc and they will 'survive' P-OPT to remain in the target file.
    As with the print mode, only the last meta-command assignment is
    retained.

    If you are outputting to a disk file, you may find the $REMRK very handy.
    It simply marks a line as a "super-remark" that will survive the P-OPT
    process to also appear in the target file.


    3.6   Meta - Command Caution

      Meta-commands are a very powerful feature of P-OPT, and should be used
    with discretion.  Using too many $REMRK 's will make the output file
    larger and wordier than necessary, defeating the purpose of P-OPT.
      In fact the only meta-cpmmand that should be used more than once is
    $REMRK:, $SUBTL: and possibly $PAGEF: if you are outputting to printer.
    The others should be assigned once.


     4.0  Outputting a source/output cross reference

        Whether you are outputting to the printer or a disk file, you can
    tell P-OPT to produce a cross reference of your script command file by
    setting $LNCNT: to a positive number in the source.

    When cross referencing, a fully optimized file is output with the
    addition of line numbers.  The SOURCE line, NOT target line.  This means
    that numbers will NOT be sequential, since simple remarks and blank
    lines are removed.  But this allows you to reference the target
    file against a commented source file at run time.

    While, this is fully optimized, the commented line numbers will slow it
    down, but as a debugging aid in large script files, this should be very
    useful.

    Sample cross reference output:

    GOTO PRGM_END                               ;Src Line #:  69
    ENDC                                        ;Src Line #:  70
    ENDS                                        ;Src Line #:  71
    BEGIN:                                      ;Src Line #:  85
    SET CR_I CR                                 ;Src Line #:  86
    SET PARI EVEN                               ;Src Line #:  87



    Though not tested, in theory, later in the file, you could toggle off
    the line numbers with a "$LNCNT:0" meta-command.


      5.0   External Data file

       All that P-OPT needs to know to run is read from the command line, but
    in the interest of flexibility, it reads the translation for long to
    short form of PROCOMM command words from an external file called (and
    hard coded as such) PROCMDS.LST.  This is created with a standard ASCII
    text editor in the format of:
                 LONGNAME,LNAM
    with the long, formal name on the left, the abbreviated form on the
    right, separated by a comma.  Note that the PROCMDS.LST you should have
    recieved with P-OPT.EXE may or may not be a complete list of PROCOMM
    command words!  Look thru it compared to the PROCOMM docs and edit as you
    need.

    DO NOT ADD ANY COMMANDS THAT ARE UNDER 5 CHARACTERS LONG!  Adding
    words like RGET and SEND or FIND to the list is pointless, first because
    they do not have a shorter abbreviation, second P-OPT ignores anything
    under 4 characters long, third adding them just for the sake of adding
    them will cause P-OPT to require more memory, and it will take it longer
    to search the larger array of command words.



       In utilizing an external data file, the programming was done "blind".
    That is, P-OPT works by a set of rules rather than acting in response to
    specific words.  This means that only if (when?) the PROCOMM script
    language changes would you outgrow P-OPT. Also in using an external
    text file, some added features are available and explained later.



     6.0  Advanced features

       Most of the best parts of P-OPT will never be seen by you.:

    Since there are some BBS out there that still require a semi colon top
    stack commands, P-OPT will check to see if a line with a ";" in it is
    inside a quote and if so, leave it alone.

    However, if an additional remark trails a quoted semi colon, it will be
    stripped whether in a quote or not.

    In scooting quoted literals to the left (TRANSMIT "password" becoming
    TRANS"password"), P-OPT looks to see that they is a space preceeding the
    first quote, and if so, only then is it supposed to scoot it to the
    left.

    P-OPT is not case sensitive, either in the original source file, or the
    PROCOMM data command file.  P-OPT will convert the source line to upper
    case, maul it to death, then output the result.  The output will NOT be
    converted to upper case however.  The output will be the literal from
    the source file AND from the PROCMDS.LST data file.  If you use lower
    case in the data file, and some upper in the source file, P-OPT will (in
    spite of you) make a match and replace it successfuilly, but the target
    (output) file will be in mixed case.



    Most all of PROCOMM's command key words are the first command on a line,
    the obvious exceptions of SET and IF.  In the interest of speed,  P-OPT
    first looks for a meta-command, then strips blanks and then looks at
    the first word for optimization.  If that word is "SET" or "IF" then it
    shifts to the next word to optimize.  If the first is "IF" and the second
    is "NOT" then it shifts to the third word.


    In all cases nothing right of a quote is optimized, so that if you are
    RGETing of FINDing something, it will look for what ever you have quoted.


    Note: If you have a specific application that leaves unoptimized command
    words in the optimized (output) line, I would like to know about it and
    see an example or two, as this algorithm is not etched in stone, but
    it is just about as quick as I can make it.



    6.1   Advanced meta-command usage

    When used with the printer as an output, whatever your source file has
    assigned to $AUTHR:, $TITLE: and $SUBTL: as well as $VERSN: will be
    printed at the top of each page along with a page number.

    As noted, meta-commands can be reassigned throughout the command file.
    This means that for print formatting, aside from just inserting the
    $PAGEF: meta-command to force a form feed, you could also PRIOR to the
    form feed, reassign $SUBTL: meta-command to assign a separate subtitle
    for each page holding a specfic routine.

      Irregardless of their placement in the source file, P-OPT should read
    and act on all meta commands as encountered, as long as they start in
    column one.  The reason for needing to declare them in the first 10
    lines of the source for starters, is so that BEFORE P-OPT goes to output
    the first few lines, it needs to know things like $LNCNT: and $PGSIZ:
    and so forth.  To accomplish this, P-OPT "pre-reads" the first few (10)
    lines to get these parameters, then it starts over to actually optimize
    the file.

      After that, meta-command parameters can be changed on the fly to allow
    you to go so far as to print easch routine on a separate page ($PAGEF:)
    and even $SUBTL: each page with a different name.

    Finally, the new QMODEM 3.0 just came out, with a greatly enhanced
    script language, and it appears that you could edit the PROCMDS.LST to
    allow some possible translations from PROCOMM to QMODEM.  That is,
    PROCOMM uses TRANSMIT to signal the system to send a literal or a string,
    QMODEM uses SEND.  In your PROCMDS.LST you could edit a copy to read:
    TRANSMIT,SEND

    Converting back from QMODEM to PROCOMM probably will not work because
    most of QMODEM's words seem to be 4 chars long or less already. eg
    SEND,TRANS
    would not work because "SEND" would be ignored being under 5 chars long.
    Additionally, aside from not knowing if QMODEM even recognizes
    shorter versions of the key words, it looks like P-OPT's meta-commands
    might choke Qmodem or vice versa since they both use the "$word" format.



    7.0   Future Releases

       One of the most powerful and features of P-OPT are it's meta-commands.
    I toyed with one for printer codes, but they are too variable and it is
    easier for you to set it into conpressed print, or whatever than me,
    given the variety of printers.

       However, if you have a suggestion for additional meta-commands, call
    my board and leave a note, and we will look into it.  I do plan a relase
    soon with enhanced titling especially in the print mode, but as an
    optimizer per se it seems to work very well.  I also think I can triomn a
    few seconds here and there if I tried real hard.





    8.0  Acknowledgements

       QMDOEM is Copyright John Friel
       PROCOMM is Copyright DATASTORM
       VERSA is Copyright Allen Brunson

    P-OPT is Copyright InfoSoft, 1987,      ALL RIGHTS RESERVED


    P-OPT is Copyrighted, but no "donations" or "contributions" are
    solicited for it, nor is the source code available for sal

    P-OPT may not be sold, even for nominal (or otherwise) so-called disk
    fee, nor may it be included in any library, collection.  It may not
    be offered for a donation or for monetary remuneration of any sort
    or included in a collection of programs by any organization either
    for-profit or non-profit.  P-OPT must also be distributed with
    this documention in uneditted form.


       Special Thanks to Allen Brunson, without who's need for something to
    optimize VERSA, P-OPT would never have been conceived.

       P-OPT is written in QuickBASIC 2.01
       All routines used in P-OPT were written by me or are from my own
    library of routines except for EXIST (to check if a file exists).


    9.0  History

    April 28, 1987   - Released  Version 1.0